Psion Series 3 Software Development Alasdair Manson Psion Inc. 73733.32@compuserve.com COPYRIGHT(C) 1994 BY CREATIVE DIGITAL SYSTEMS. ALL RIGHTS RESERVED> Series 3 and 3a applications may be developed either in OPL or C. The facilities available in both languages are such that, whichever language you use, there need not be any great difference in the appearance of the application to the user. OPL is a BASIC-like high level language which is tokenized for runtime interpretation. The OPL language has about 270 commands and functions which should seem very familiar to programmers in other high level languages. Generally speaking, an application written in C is more responsive and may use less memory than one written in OPL. Large applications, or those that are critically dependent on speed will benefit from being written in C, which provides the potential to create a more sophisticated application than is practical in OPL. OPL should not, however, be ruled out by serious developers. Development in OPL involves a much smaller learning curve, particularly if the programmer is not already familiar with the C language and it is possible to prototype and develop applications very rapidly. Development for OPL programmers Although OPL programs can be developed on the Series 3 itself, it's impractical. To develop in OPL for the Series 3 I recommend the following: *a Series 3 or Series 3a and its Programming Manual; *an IBM PC or compatible; *a text or program editor, such as Brief, to run on the PC; *a PC version of the Psion 3Link cable and the associated software; *optionally, a Series 3 or Series 3a emulator to run on the PC; *optionally, the HC OPL/g SDK which provides a PC environment for developing OPL programs; Although primarily aimed at developers writing for the Psion HC range of machines, the majority of the information in the SDK is applicable to developing OPL programs for any Psion computer. The version of OPL supplied on Series 3 and Series 3a computers is a superset of the OPL/g version that is described in this SDK. The SDK also has useful software tools and an extensive OPL code library. *optionally the Documentation version of the SIBO (SIngle Board Organizer) C SDK, which contains a lot of general material that is useful to an OPL programmer. There is a close parallel between the actions of OPL keywords and facilities provided when you're programming in C. Further, programmers wishing to use asynchronous I/O (with keywords such as IOA and IOWAIT) can find a great deal of useful background information in these manuals. In addition to these manuals, the Series 3 OPL development environment on the PC consists of the OPL program translator HHTRAN.EXE. This is supplied, together with explanatory documentation, with the HC OPL/g SDK. It is also provided, together with an explanatory text file, as part of the 3Link software. Using this development environment, a program can be written and translated on the PC. If a Series 3 emulator is available, initial testing may also be carried out on the PC. For final testing the program must be transferred, via 3Link, to a Series 3. Development for C programmers An application written in C must be developed on a PC. For this you need: *a Series 3 or Series 3a; *an IBM PC or compatible; *a text or program editor, such as Brief, to run on the PC; *a PC version of the Psion 3Link cable; *at least those elements of Clarion TopSpeed C and the Psion C development environment that are provided by the Standard version of the SIBO C SDK; and *optionally, a Series 3 or Series 3a emulator to run on the PC. CLIB or PLIB? An application developed in C may make use of either of two C libraries: CLIB or PLIB. CLIB contains standard functions, familiar to most C developers, and described in TopSpeed's C Library Reference manual. A developer who wishes to port an existing application to a SIBO machine with a minimum amount of effort would use CLIB. A pure CLIB program is, however, restricted to a much simpler user interface than a PLIB program. The PLIB library is more closely matched to the EPOC architecture and, in general, results in a smaller program than the equivalent CLIB version. In addition, it provides access to many of the EPOC system services that are not available in CLIB. There is, however, more to learn for a programmer already familiar with standard C libraries. A compromise route is possible, since a CLIB program may also use PLIB functions. Developing applications using PLIB is the same as creating programs using a large, non-portable, C library. For example, the lines of C which you might write as: char target; int len; strcpy(target, "Hello world"); if (strlen(target) > 10) printf("Value %d is too large", len); would, in a PLIB program look like this: TEXT target; p_scpy(target, "Hello world"); if (p_slen(target) > 10) p_printf("Value %d is too long", len); As you can see, there is a close parallel. Object-Oriented Programming Developers writing for the Series 3 and Series 3a machines may choose to write their applications with the aid of Psion's Object Oriented programming system. This is the system used by Psion to develop application software. Applications written using this system can make use of the extensive object-oriented libraries that are built into the ROM of all Series 3 machines. As a result, such applications can be more sophisticated and flexible than those written in straight C. The C Development Process Programs are written on the PC, using either the TopSpeed Environment or another program editor, such as Brief. When successfully compiled and linked, the program is transferred to, and run on, the Series 3. This can conveniently be done with the aid of the SIBO debugger that is provided with the C SDK. Those parts of the software that do not depend on user interface code specific to the Series 3 may be debugged locally, on the PC. If a Series 3 or Series 3a emulator is available, initial testing may also be carried out on the PC, but final testing must take place on the target machine. The Psion SIBO C Software Development Kit The Psion SIBO C Software Development Kit provides the information necessary to develop C language applications for the Psion SIBO family of handheld and notebook computers, including the Series 3 and 3a. The C SDK is available in three variants: Documentation (Doc), Standard (Std) and Professional (Prof). SIBO C SDK (Doc) The Documentation variant contains: *three volumes of SDK documentation, containing fourteen manuals, *the Psion software environment, including libraries, header files and associated software tools, and *example program source code that relates to the documentation. This variant is not sufficient by itself to develop SIBO applications in C. It is suitable for the following reasons: *you already have the Clarion TopSpeed C package; *you require additional copies of the documentation, say, for design purposes; *you wish to upgrade to a later version of the SDK; *you wish to evaluate the SDK development environment; or *you intend to develop applications in OPL. SIBO C SDK (Std) In addition to the material supplied in the Documentation variant, the Standard variant contains: *TopSpeed C, the Clarion C compiler and library, and *TopSpeed Environment, the Clarion multi-window editor and project system. This variant contains all the system software necessary to develop SIBO applications in C. The TopSpeed C components may be used independently of the Psion SDK components both to learn C programming and to write C programs to run on a PC. This variant is suitable if: *you intend to develop C applications for any of the SIBO range of computers, or *you do not already have the TopSpeed C package. SIBO C SDK (Prof) In addition to the material supplied in the Documentation and Standard variants, the Professional variant contains: *the Clarion TopSpeed TechKit, including the TopSpeed assembler, *the Clarion TopSpeed C Library Source Kit, containing the source code (both C and assembler) for the C library that is supplied with the compiler, and *Psion SIBO CLIB C library source. This variant is suitable for the following reasons: *you develop substantial applications for the PC as well as for SIBO machines, *you wish, or need, to write at least part of your code in assembly language, or *you need to have control over the C library. C SDK documentation The C SDK documentation, which comes with all three variants of the SDK, consists of fourteen manuals, in three volumes, covers a wide range of SIBO architectural features and the SIBO development system. General Programming Manual This manual explains how to install the SDK and how, by means of simple examples, to build an application that run on a SIBO machine. It describes in detail the differences between the CLIB and PLIB C libraries and also gives guidance on copy protection. The important Fundamental Programming Guidelines chapter explains the basic principles that should be understood by all developers of SIBO applications. It includes advice on how to ensure that an application remains responsive to user input and is robust against runtime errors, such as shortage of memory. The SIBO Debugger The SIBO C source-level debugger, supplied with all variants of the SDK, runs on a PC. It is normally used for remote debugging of an application running on a SIBO machine but may, in some circumstances, also be used to debug SIBO applications running on the PC. The debugger is specifically designed to facilitate the debugging of applications running in the EPOC environment, in which the application's code segment may be relocated at any time. This manual describes the facilities provided by the SIBO debugger and explains its use. HC Programming Guide This manual contains information that is specific to the development of applications for the rugged and highly configurable HC range of computers. The topics include Writing Software for the HC, The HC Command Shell and Customizing the HC ROM. Series 3/3a Programming Guide This manual contains information that is specific to the development of applications for the Series 3 and 3a computers. The topics include: *Series 3 Programming Overview - including advice on writing multilingual applications. *Communicating with the System Screen - including the differences between file-based and non-file based applications, the receipt by an application of Shutdown and Switchfiles messages, and the modification of an application's behavior by means of the technique of aliasing. *Enhanced Sound Output. Programming in HWIF HWIF (the Handheld Wimp InterFace) is a library of user interface routines suitable for use by C developers producing applications for the Series 3 computers. The HWIF library provides easy and efficient access to many aspects of Series 3 functionality, including sophisticated printing and the presentation of menu bars, dialog boxes and edit boxes. The manual contains a range of working examples as well as a comprehensive description of all HWIF routines. Additional System Information The Additional System Information manual explains a variety of topics, including the MCLink communications software, resource files, printer drivers, the file formats used by applications and the writing of device drivers. PLIB Reference This manual contains a comprehensive description of the PLIB C function library. The library routines are classified into fourteen areas of functionality and each group is accompanied by background information, usage recommendations and example code. Window Server Reference This manual contains a description of the WLIB library. This library provides an interface to the window server built into each SIBO machine, supplying a range of sophisticated graphics operations. The topics discussed include: Windows, Graphics output, Keyboard input, Bitmaps and Text fonts. Again, the descriptions are accompanied by example code. I/O Devices Reference This manual describes the I/O device drivers that have been written by Psion. The description of each driver includes a full explanation of the services that it supports, together with example code. ISAM Reference The ISAM (Indexed Sequential Access Method) dynamic library provides a powerful set of functions to access record and field-structured files of the type that are manipulated by OPL programs and the database applications on SIBO machines. The ISAM Reference manual explains, with the aid of example code, how to load and use the ISAM library, and contains a complete description of the ISAM functions. EPOC O/S System Services This manual contains a complete description of the software interrupt interface to ROM-based system services, classified into 21 areas of functionality. An appendix lists the services both alphabetically, by service name, and numerically, by interrupt and function number. This are of particular interest to OPL and assembly-language programmers. Hardware Reference The Hardware Reference manual contains a description of the SIBO computer hardware, including the principal chip set, expansion ports and the SIBO serial protocol. Object-Oriented Programming Guide The Object-Oriented Programming Guide describes the tools and techniques needed to design and develop object-oriented applications for Series 3 and Series 3a machines with the aid of Psion's object-oriented programming system. It is a practical guide to writing of object-oriented applications and contains many code examples. This manual explains the use of the basic window, menu, dialog and event-management classes, and the handling of and recovery from errors. More advanced topics include the editing of formatted text and access to the printer services. OLIB Reference The OLIB Reference manual contains a full description of all the object classes included in the OLIB object library. This library provides the basic control mechanisms that are common to all object-oriented applications, together with a wide range of data and file management classes. Topics include: *Variable Array Classes (container classes) *Timers *Editable Documents *File Management *Resource Files *Inter-process Communication Developer kits and information can be obtained from Psion at 508.371.0310 (Concord, MA), 415.951.4764 (San Francisco, CA), 312.419.5300 (Chicago, IL) and 071.262.5580 (London, UK). 4 Parts and Prices SIBO SDK Documentation version (part 1505-0014) $100 SIBO SDK Standard version (part 1505-0013) $325 SIBO SDK Professional version (part 1505-0012) $620 OPL/g SDK (part 1505-0010) $100 Ali worked in the Technical Support Department of Psion plc for 3.5 years before joining Psion Inc. as Technical Manager in 1993. He hails originally from Edinburgh, Scotland where he misses, among other things, Edinburgh Hibernian FC and pints of heavy. He recently skydived for the first time and would recommend it to anybody whose life is becoming a bit prosaic.